Creating Sequence Grabber Panel Components(IM: QC)

Inside Macintosh: QuickTime Components /: Chapter 7 - Sequence Grabber Panel Components

Creating Sequence Grabber Panel Components
This section discusses how to create a sequence grabber panel component. You should read this section if you are creating a panel component.
Applications do not call panel components directly. Rather, they invoke a sequence grabber's settings dialog box by calling the SGSettingsDialog function. In response, the sequence grabber presents the settings dialog box to the user. When the user selects a specific settings panel, the sequence grabber invokes the appropriate panel component.
Panel components provide a number of functions that allow sequence grabbers to manage their relationships with panel components. See "Managing Your Panel Component" beginning on page 7-15 for complete descriptions of these functions.
Panel components are not responsible for saving their settings information.
Sequence grabbers manage this information on behalf of panel components,
and a sequence grabber may combine configuration information from several panel components in order to build up the complete configuration for an elaborate digitizing environment. Panel components provide functions that allow sequence grabbers to obtain this configuration information. See "Managing Your Panel's Settings" beginning on page 7-24 for more information about these functions.
Sequence grabbers store this configuration data in user data items. The Movie Toolbox provides a number of functions that allow you to create and manage user data items. If you are not familiar with these functions, see the chapter "Movie Toolbox" in Inside Macintosh: QuickTime for more information.
Apple has defined a component type value for sequence grabber panel components. You can use the following constant to specify this component type.
#define  SeqGrabPanelType 'sgpn' /* panel component type */
Sequence grabber panel components use their component subtype and manufacturer values to indicate the type of configuration services they provide. The subtype value indicates the media type supported by the panel component. This value should correspond to the component subtype value of channel components that may be configured by the panel component. For example, a panel component that manages video settings would have a subtype of 'vide' (this value is defined by the Movie Toolbox's VideoMediaType constant).
The manufacturer field contains a unique identifier for each panel component. The value should indicate something about the specific services provided by the component. For example, Apple has defined the following manufacturer values:
#define  SeqGrabCompressionPanelType   'sour'   /* input source
                                                   selection */
#define  SeqGrabSourcePanelType        'cmpr'   /* compression
                                                   settings */
In general, Apple has reserved all lowercase values of component subtypes and manufacturer codes.
Apple has defined a functional interface for sequence grabber panel components. For information about the functions that your component must support, see "Sequence Grabber Panel Components Reference" beginning on page 7-14. You may use the following constants to refer to the request codes for each of the functions that your component must support:
enum {
   /* sequence grabber panel request codes */

   kSGCPanelGetDitlSelect        = 0x200, /* SGPanelGetDITL */
   kSGCPanelCanRunSelect         = 0x202, /* SGPanelCanRun */
   kSGCPanelInstallSelect        = 0x203, /* SGPanelInstall */
   kSGCPanelEventSelect          = 0x204, /* SGPanelEvent */
   kSGCPanelItemSelect           = 0x205, /* SGPanelItem */
   kSGCPanelRemoveSelect         = 0x206, /* SGPanelRemove */
   kSGCPanelSetGrabberSelect     = 0x207, /* SGPanelSetGrabber */
   kSGCPanelSetResFileSelect     = 0x208, /* SGPanelSetResFile */
   kSGCPanelGetSettingsSelect    = 0x209, /* SGPanelGetSettings */
   kSGCPanelSetSettingsSelect    = 0x20A, /* SGPanelSetSettings */
   kSGCPanelValidateInputSelect  = 0x20B  /* SGPanelValidateInput */
};
Before reading the rest of this chapter, you should know how to create components. See the chapter "Component Manager" in Inside Macintosh: More Macintosh Toolbox for a complete discussion of components, how to use them, and how to create them.
The next section contains sample code for the creation of a sequence grabber panel component that acts as a settings dialog box for PICT images. To create a sequence grabber panel component, you set up the global variables and implement the required Component Manager request codes and the functions that are private to your
particular component. Then you manage the dialog box and work with the settings in the dialog box.

Implementing the Required Component Functions
Listing 7-1 supplies the component dispatchers for the sequence grabber panel component together with the required functions for open, close, can do, and version.
Listing 7-1 Implementing the required functions
#define sgcPictShowTicksType 'TICK'
typedef struct {
   ComponentInstance    self;
   ControlHandle        ch;
} PictPanelGlobalsRecord, *PictPanelGlobals;
/* only for PICT channels */
pascal ComponentResult SGSetShowTickCount (SGChannel c, 
               Boolean show) = {0x2f3c,2,0x100,0x7000,0xA82A};
pascal ComponentResult SGGetShowTickCount (SGChannel c, 
               Boolean *show) = {0x2f3c,4,0x101,0x7000,0xA82A};
pascal ComponentResult PictPanelDispatcher
               (ComponentParameters *params, Handle storage)
{
   OSErr err = badComponentSelector;
   ComponentFunction componentProc = 0;
   switch (params->what) {

      case kComponentOpenSelect: 
         componentProc = PictPanelOpen; break;
      case kComponentCloseSelect: 
         componentProc = PictPanelClose; break;
      case kComponentCanDoSelect: 
         componentProc = PictPanelCanDo; break;
      case kComponentVersionSelect: 
         componentProc = PictPanelVersion; break;
      case kSGCPanelGetDitlSelect: 
         componentProc = PictPanelPanelGetDitl; break;
      case kSGCPanelInstallSelect: 
         componentProc = PictPanelPanelInstall; break;
      case kSGCPanelItemSelect: 
         componentProc = PictPanelPanelItem; break;
      case kSGCPanelRemoveSelect: 
         componentProc = PictPanelPanelRemove; break;

      case kSGCPanelGetSettingsSelect: 
         componentProc = PictPanelPanelGetSettings; break;
      case kSGCPanelSetSettingsSelect: 
         componentProc = PictPanelPanelSetSettings; break;
   }

   if (componentProc)
      err = CallComponentFunctionWithStorage (storage, params,
                                              componentProc);

   return err;
}

pascal ComponentResult PictPanelCanDo (PictPanelGlobals store,
                                        short ftnNumber)
{

   switch (ftnNumber) {
      case kComponentOpenSelect: 
      case kComponentCloseSelect: 
      case kComponentCanDoSelect: 
      case kComponentVersionSelect: 
      case kSGCPanelGetDitlSelect: 
      case kSGCPanelInstallSelect: 
      case kSGCPanelItemSelect:
      case kSGCPanelRemoveSelect: 
      case kSGCPanelGetSettingsSelect: 
      case kSGCPanelSetSettingsSelect: 
         return true;
      default:
         return false;
   }
}

pascal ComponentResult PictPanelVersion (PictPanelGlobals store)
{
   return 0x00020001;
}
pascal ComponentResult PictPanelOpen (PictPanelGlobals store,
                                        ComponentInstance self)
{
   OSErr err;
   /* allocate global variables */
   store = (PictPanelGlobals) NewPtrClear
            (sizeof(PictPanelGlobalsRecord));
   if (err = MemError()) goto bail;
   SetComponentInstanceStorage (self, (Handle)store);
   /* remember the component instance identification number */
   store->self = self;

bail:
   return err;
}

pascal ComponentResult PictPanelClose (PictPanelGlobals store,
                                       ComponentInstance self)
{
   if (store) DisposePtr ((Ptr)store);
   return noErr;
}
Managing the Dialog Box
This section gives details on the functions that the panel component must provide so that the sequence grabber can load the component's items into the settings dialog box and receive and process dialog events.

To prepare to add the component's items to the settings dialog box, the sequence grabber obtains the item list by calling the SGPanelGetDITL function (described on page 7-18).
Once it has installed the items, the sequence grabber calls the SGPanelInstall function (described on page 7-19), which sets up the state of the dialog box
(for example, a checkbox) and gives the panel component an opportunity to set initial values.
When the panel component is loaded into the settings dialog box and active, it may receive and process dialog events and mouse clicks. The component's SGPanelEvent function (described on page 7-22) processes individual dialog events.
Whenever the user clicks a dialog item, the sequence grabber calls the SGPanelItem function (described on page 7-21).
Before the sequence grabber removes the items from the settings dialog box, it calls the SGPanelRemove function (described on page 7-20).

Listing 7-2 provides an example of the management of the settings dialog box for a sequence grabber that displays PICT images. The component item displayed in the dialog box in this case is a tick count checkbox.
Listing 7-2 Managing the settings dialog box
pascal ComponentResult PictPanelPanelGetDitl 
                                    (PictPanelGlobals store,
                                     Handle *ditl)
{
   /* 
      Get and detach the dialog box template. Note that 
      the sequence grabber has already opened the resource file. 
   */
   *ditl = GetResource ('DITL', 7001); 
   if (!*ditl) return resNotFound;
   DetachResource (*ditl);
   return noErr;
}

pascal ComponentResult PictPanelPanelInstall 
                        (PictPanelGlobals store, SGChannel c,
                         DialogPtr d, short itemOffset)
{
   Rect r;
   short kind;
   Handle h;
   Boolean ticksShowing;

   /* set up the initial state of the checkbox */
   GetDItem (d, 1 + itemOffset, &kind, &h, &r);
   store->ch = (ControlHandle)h;
   SGGetShowTickCount (c, &ticksShowing);
   SetCtlValue (store->ch, ticksShowing);

   return noErr;
}

pascal ComponentResult PictPanelPanelItem 
                        (PictPanelGlobals store, SGChannel c,
                         DialogPtr d, short itemOffset, 
                         short itemNum)
{
   /* if the item clicked was your checkbox, update its state */
   if ((itemNum - itemOffset) == 1) {
      Boolean showing = GetCtlValue (store->ch);
      SetCtlValue (store->ch, !showing);
      SGSetShowTickCount (c, !showing);
   }

   return noErr;
}

pascal ComponentResult PictPanelPanelRemove 
                              (PictPanelGlobals store, 
                              SGChannel c, DialogPtr d, 
                              short itemOffset)
{
   /* forget that it ever had a control */
   store->ch = nil;
   return noErr;
}
Managing Your Panel's Settings
To allow the sequence grabber to work with your panel's settings, your panel component must allow the sequence grabber to

retrieve the panel's current settings by calling your SGPanelGetSettings function (described on page 7-24)
restore those settings to some previous values by using your SGPanelSetSettings function (described on page 7-25)

Listing 7-3 gives an example in which the settings are managed in a user list that contains tick count information for a panel component for PICT images.
Listing 7-3 Managing the settings for a panel component
pascal ComponentResult PictPanelPanelGetSettings 
                     (PictPanelGlobals store, SGChannel c,
                      UserData *result, long flags)
{
   OSErr       err;
   UserData    ud;
   Boolean     ticksShowing;
   /* create a user data list containing your state */
   if (err = NewUserData (&ud)) goto bail;
   if (err = SGGetShowTickCount (c, &ticksShowing)) goto bail;
   if (err = SetUserDataItem (ud, &ticksShowing, 
                              sizeof (ticksShowing), 
                              sgcPictShowTicksType, 1)) goto bail;

bail:
   if (err) {
      DisposeUserData(ud);
      ud = 0;
   }
   *result = ud;

   return err;
}

pascal ComponentResult PictPanelPanelSetSettings 
                           (PictPanelGlobals store, SGChannel c,
                            UserData ud, long flags)
{
   Boolean ticksShowing;

   /* restore the state from the specified user data list */
   if (GetUserDataItem (ud, &ticksShowing, 
                        sizeof (ticksShowing),
                        sgcPictShowTicksType, 1) == noErr)
      SGSetShowTickCount (c, ticksShowing);

   return noErr;
}
Subtopics
Implementing the Required Component Functions

Managing the Dialog Box

Managing Your Panel's Settings